Java知识体系

Appearance

MCP Java SDK：标准与架构全面分析

内容概览：

  1. 什么是 MCP Java SDK？
  2. MCP 的三层架构介绍
  3. 核心功能与模块（工具、资源、提示词等）
  4. 重点传输协议解读及场景应用
  5. Spring AI 与 MCP 集成方式

什么是 MCP Java SDK ？ ​

Spring AI 框架用于实现 MCP 协议的上层架构实现。

MCP Java SDK 的实现采用了三层架构设计，这种架构将应用逻辑、会话管理和底层传输进行了明确的解耦，以提高系统的可维护性和灵活性,。

以下是该架构的详细组成：

1. 客户端/服务器层 (顶部) ​

这一层处于架构的最顶端，直接面向开发者，负责处理主要的应用逻辑和协议操作,。

  • McpClient：负责管理客户端的所有操作以及与服务器的连接,。
  • McpServer：负责处理服务器端的协议操作并响应来自客户端的请求,。 这两个核心组件在运行时都会利用其下方的“会话层”来执行具体的通信管理任务,。

2. 会话层 (中间层) ​

中间层起到了承上启下的作用，主要负责管理通信模式并维护连接状态,。

  • McpSession：这是核心的会话管理接口,。
  • 具体实现：针对客户端和服务器的不同需求，SDK 提供了 McpClientSession 和 McpServerSession 两种特定的实现,。

3. 传输层 (底部) ​

传输层是整个架构的基石，负责最底层的消息传输和数据序列化,。

  • McpTransport：该组件专门管理 JSON-RPC 消息的序列化与反序列化,。
  • 多协议支持：它为各种高层次的沟通提供基础支持，能够兼容多种传输机制，包括 STDIO（标准输入输出）、HTTP/SSE 以及最新的 Streamable-HTTP 等,。

比喻理解： 如果把 MCP Java SDK 比作一个邮政系统：

  • 顶部层就像是“发件人和收件人”，他们关注的是信件的内容和目的。
  • 中间层就像是“邮局分拣中心”，负责管理信件的状态（是否挂号、是否妥投）并建立收发双方的联系。
  • 底部层则是“运输车队和道路”，无论信件是通过卡车（STDIO）、火车（SSE）还是飞机（Streamable-HTTP）运输，它们只负责将信件打成包裹（序列化）并安全送达,。
mermaid
graph TD
  A[客户端/服务器层] --> B[会话层]
  B --> C[传输层（JSON-RPC 序列化）]

总结：三层架构通过清晰划分职责，降低开发复杂性，同时提升了架构的模块化和扩展性。

声明式注解 ​

通过 Spring AI 的声明式集成，开发者极大地简化 MCC 的开发工作。

  • 核心注解：Spring AI 提供了 @McpTool（工具）、@McpResource（资源）、@McpPrompt（提示词）等注解。
  • 自动生成：@McpTool 会自动根据方法参数生成 JSON 模式 (JSON Schema)，模型利用该模式理解如何调用工具。

优势：这种声明式方法大幅减少了样板代码，提高了代码的可维护性，并能通过 Spring Boot 的自动配置实现 Bean 的自动检测与注册。

MCP 的三大核心功能 ​

  • 工具 Tools
    • 允许服务器暴露功能供大语言模型（LLM）使用。
  • 资源 Resources
    • 提供标准化的数据暴露方式。
  • 提示词 Prompts
    • 定义与优化 AI 用户交互的提示。
    • 同时支持：
      • 自动补全 (Completions)
      • 结构化日志 (Logging) 和 进度跟踪 (Progress)。

灵活的传输机制与协议 ​

模型上下文协议（MCP）支持多种传输协议，为不同的应用环境提供了极高的灵活性。

以下是四种核心传输机制的详细分析：

四种传输机制及应用场景分析 ​

  1. STDIO（标准输入输出）
    • 技术细节：这是一种进程内协议，通信通过标准输入和标准输出进行，无需额外的网络依赖。
    • 适用场景：主要用于本地主机应用、命令行工具（CLI）或桌面工具，非常适合开发者的局部通信与快速测试。
  2. SSE（服务器发送事件）
    • 技术细节：基于 HTTP 的实时事件协议，服务器作为独立进程运行，能够处理多个客户端连接。
    • 适用场景：适用于需要服务器向客户端推送实时事件的传统 Web 环境。
  3. 可流式 HTTP（Streamable-HTTP）
    • 技术细节：该协议取代了 SSE 传输，支持通过 HTTP POST 和 GET 请求进行持久连接管理和实时通知。
    • 适用场景：相比 SSE，它更适合云原生环境，能更高效地处理多个客户端连接并支持动态变更通知。
  4. 无状态协议（Stateless）
    • 技术细节：设计上请求之间不保持会话状态，旨在简化部署并提升系统水平扩展能力。
    • 适用场景：专为微服务架构和云原生部署优化，是分布式系统追求高度灵活性时的理想选择。
mermaid
flowchart TD
  A[STDIO] -->|进程内/本地| E[本地应用与命令行工具]
  B[SSE] -->|HTTP实时推送| F[传统独立进程服务]
  C[可流式 HTTP] -->|持久连接/取代SSE| G[现代云原生环境]
  D[无状态协议] -->|无会话状态| H[微服务与分布式部署]

  E -.->|开发者调试| I[本地开发阶段]
  G -.->|高可靠通知| J[生产云系统]
  H -.->|简化扩展| J

案例对比：

  • STDIO 模式下，服务器通常在主机应用内运行，最适合开发者在本地环境中进行工具和资源的调试。
  • Streamable-HTTP 与无状态协议 则将服务器作为独立进程处理，通过非阻塞和无状态化设计，更好地服务于多进程、高通量的云端分布式系统。

思考与自测❗ ​

思考问题：

  1. MCP 的三层架构如何帮助提升通信的灵活性？
  2. Statless 的协议为何对云原生环境更友好？
  3. Spring AI 的自动注册功能在开发过程中如何起作用？

自测题：

  1. MCP SDK 提供了哪些工具调用案例？
  2. JSON-RPC 的传输机制与哪种层次直接相关？
  3. Spring AI 的 @McpPrompt 注释主要解决什么问题？